test(expo): add the Expo end-to-end test package and the verify-clerk-expo skill - #10087

Description

Adds end-to-end tests that prove a @clerk/expo change on an iOS simulator or an Android emulator, and a CLI that runs them, as the Node package integration/expo-native/.

The tests are an ordinary e2e project. npx e2e run <test file> runs one when the environment names the platform, a booted simulator or a running emulator by its id, a build of the expo-native fixture, and the publishable key and secret key of a Clerk development instance. integration/expo-native/README.md has the commands. The tests launch the fixture with the inputs from #10052.

The CLI sits on top of the tests. It builds the fixture, runs the tests against a Clerk application that it creates and deletes, and keeps a video and screenshots of each run. The device is on the machine that runs the CLI. Under the CLI the test process never holds the application's secret key. The verify-clerk-expo skill is the instructions an agent or a developer reads, and they point at the package.

It sits on #10052. #10090, on top of this, runs these tests in CI and deletes the older tests in integration/tests/expo-native/, which this pull request leaves as they are. #10131, on top of #10090, lets a machine that cannot run a device borrow one on a CI runner.

The seven commits are in dependency order, and each adds one part. Paths below that begin src/, specs/, or .verify/ are inside integration/expo-native/.

Commits 2 and 3, e2e.config.ts in commit 1, specs/fixtures.ts in commit 5, and most of commit 6 are the same files, byte for byte, in clerk/clerk-ios#629 and clerk/clerk-android#1046. src/core/MANIFEST lists every shared file with its hash, and a unit test fails when one drifts. Review them once. The unit tests for all of the code arrive together in commit 6, so the commits before it do not pass a test run by themselves.

The skill is SKILL.md, references/, and one page per feature in features/, all in .claude/skills/verify-clerk-expo/, and .cursor/skills/verify-clerk-expo is a symlink to that directory. To review what is this repository's own, read SKILL.md, then src/host.ts and src/fixture.ts, then specs/app.ts and specs/golden/.

To try it on a Mac with Xcode, Node 24.8 or newer, and the team's Clerk Platform API key:

$ pnpm install
$ npm ci --prefix integration/expo-native
$ integration/expo-native/bin/control-clerk-expo doctor --platform ios
$ integration/expo-native/bin/control-clerk-expo run native-auth-view --platform ios
$ integration/expo-native/bin/control-clerk-expo down

doctor only reads, and prints a fix for each thing the machine lacks. run builds the fixture as a Debug dev client, creates the application, takes a simulator that the CLI cloned for itself, starts Metro and tsdown --watch in packages/expo, and runs the tests. A later JS edit reaches the app on the next run with no native build. down releases the device and deletes the application. The evidence stays in .verify/runs/<run-id>/.

The 17 end-to-end tests are in specs/golden/, in seven groups. Two are for iOS only, so Android runs 15.

Every test starts at the fixture's home and taps to the screen it needs, as a user would. The options of host.launch choose who is signed in, the mode of AuthView, and whether storage is kept from the last launch. specs/native.ts holds the locators of the home's buttons, and a unit test fails when they differ from the fixture's.

The tests assert on what a user sees, in the prebuilt views first and on the fixture's home for the outcome of a flow. Android tests find the prebuilt views by text, because the clerk-android release that @clerk/expo pins has no test tags. iOS tests use the clerk.* accessibility identifiers. Tests type only +clerk_test addresses and the test code 424242.

The two native-modules tests sign no one in. The Google test proves that the hook reads the fixture's placeholder client IDs and that the native module opens Google's sign-in. On iOS it also proves that a cancel comes back as Google sign-in was cancelled. On Android it stops once a page of Google Play services is on screen, because what that page is and whether Back closes it differ from run to run on an emulator with no Google account. It does not prove that a Google account can sign in. The biometrics test turns biometric sign-in on for the instance through the settings file beside it and expects the answer the native module gives on a simulator or an emulator. It does not prove enrolling or signing in with a biometric.

Each worktree gets one Clerk application in a workspace that holds nothing else, with the settings in src/core/instances/base.json. The CLI creates it with the Platform API key, which comes from the environment, a file, or a 1Password reference kept outside the repository. No file holds the application's secret key. Under the CLI the tests reach Clerk's Backend API through a stand-in on the same machine, in src/core/broker.ts, which forwards only the three kinds of request they make, for test users of that run. After a run, the CLI searches the run directory for every secret the run used, and attach refuses to post a run that holds one.

The tests' config also sets up e2e's built-in agent, with anthropic/claude-haiku-5.5 and openai/gpt-6-luna-fast as its backup, only when the environment has a Vercel AI Gateway key. No committed test uses the agent, and no workflow passes a key.

The package installs its dependencies with npm ci from its own lockfile, outside the pnpm workspace. The Expo Native Runner Tests job added to ci.yml runs the package's 498 unit tests and tsc on Linux, with no device and no secret, when a pull request changes the package or a path its tests read.

Nothing in this pull request runs a test on a device in CI. The workflow in #10090 runs the 17 tests on a commit that contains this one.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other: test tooling

🤖 Generated with Claude Code